Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Overhaul code example guidelines #28017

Merged
merged 5 commits into from
Jul 29, 2023
Merged

Overhaul code example guidelines #28017

merged 5 commits into from
Jul 29, 2023

Conversation

queengooborg
Copy link
Collaborator

This PR overhauls the guidelines for writing code examples to better match our rules today. Namely, it performs the following:

  • Renames "styling" to "writing", both because Prettier handles most styling and because the pages are more broad than just styling
  • Restructures the Shell prompt page to match the other three languages
  • Adds a "Choosing a syntax language" section
  • Removes all guidelines that are covered by Prettier's formatting

@queengooborg queengooborg requested review from a team as code owners July 17, 2023 23:55
@queengooborg queengooborg requested review from bsmth, Josh-Cena and estelle and removed request for a team July 17, 2023 23:55
@github-actions github-actions bot added Content:JS JavaScript docs Content:Glossary Glossary entries Content:Meta Content in the meta docs Content:Learn:CSS Learning area CSS docs labels Jul 17, 2023
@github-actions
Copy link
Contributor

This pull request has merge conflicts that must be resolved before it can be merged.

1 similar comment
@github-actions
Copy link
Contributor

This pull request has merge conflicts that must be resolved before it can be merged.

@github-actions github-actions bot added the merge conflicts 🚧 [PR only] label Jul 17, 2023
@github-actions github-actions bot removed the merge conflicts 🚧 [PR only] label Jul 17, 2023
@github-actions
Copy link
Contributor

github-actions bot commented Jul 17, 2023 •
edited
Loading

Preview URLs (6 pages)
Flaws (1)

Note! 5 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
Title: Guidelines for writing code examples
Flaw count: 1

  • broken_links:
    • Can't resolve /en-us/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#Example_code_blocks
External URLs (6)

URL: /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
Title: Guidelines for writing code examples

URL: /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS
Title: Guidelines for writing CSS code examples

URL: /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell
Title: Guidelines for writing shell prompt code examples

(comment last updated: 2023-07-26 23:19:30)

@Josh-Cena
Copy link
Member

I find the rename from "code style guide" to "code examples" unnecessary. Is it for any tangible concerns? The "style" does not imply "formatting".

@queengooborg
Copy link
Collaborator Author

I find the rename from "code style guide" to "code examples" unnecessary. Is it for any tangible concerns? The "style" does not imply "formatting".

As I mentioned above, our documentation covers more than just styling the examples, but rather also discusses writing conventions to follow, such as how to write variable names, where to place comments, etc. The CSS page is a great example of this, where it tells the writer what type of units to use, to not use resets, etc. As such, I personally find it misleading to call it the "styling" guide.

@Josh-Cena
Copy link
Member

"Code style" is not "code styling" ^^ "Code style" encompasses what syntax to use/not use and how code should be structured. For example, Airbnb style guide

@queengooborg
Revert document move
8495e38 
I don't really agree with returning this to the original location, but IDC anymore.
@github-actions github-actions bot removed Content:JS JavaScript docs Content:Glossary Glossary entries Content:Learn:CSS Learning area CSS docs labels Jul 24, 2023
estelle
estelle reviewed Jul 26, 2023
View reviewed changes
Copy link
Member

@estelle estelle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a few minor tweaks, two corrections, and a few suggestions for updates on text you didn't actually change

files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md Outdated Show resolved Hide resolved
files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md Outdated Show resolved Hide resolved
files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md Outdated Show resolved Hide resolved
files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md Outdated Show resolved Hide resolved
files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md Outdated Show resolved Hide resolved
files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md Outdated Show resolved Hide resolved
files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md
@@ -160,20 +141,20 @@ These guidelines should be followed to ensure that the code examples you write d
color: rgb(248, 242, 230);
```

- If you have to use hex colors, then use lower-case:
- For hex colors, use the short form where relevant:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i disagree with this one.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This guideline has been around for a long time; I didn't add it. :P

files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md Show resolved Hide resolved
files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md Outdated Show resolved Hide resolved
files/en-us/mdn/writing_guidelines/writing_style_guide/index.md Outdated Show resolved Hide resolved
@queengooborg queengooborg merged commit 9e804dd into main Jul 29, 2023
7 checks passed
@queengooborg queengooborg deleted the code-example-guidelines branch July 29, 2023 01:08
@bsmth bsmth mentioned this pull request Dec 15, 2023
Closed
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 1, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@bsmth bsmth bsmth left review comments

@estelle estelle estelle approved these changes

@Josh-Cena Josh-Cena Awaiting requested review from Josh-Cena Josh-Cena was automatically assigned from mdn/yari-content-javascript

Assignees
No one assigned
Labels
Content:Meta Content in the meta docs
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@queengooborg @Josh-Cena @estelle @bsmth